Plugin Support for Java SDK #2761

donald-pinckney · 2026-01-14T14:41:18Z

Plugin System for Java Temporal SDK

What was changed

Added a plugin system for the Java Temporal SDK, modeled after the Python SDK's plugin architecture but adapted to Java idioms.

New Files (`temporal-sdk/src/main/java/io/temporal/common/plugin/`)

ClientPlugin.java - Client-side plugin interface
WorkerPlugin.java - Worker-side plugin interface
PluginBase.java - Convenience base class implementing both
SimplePluginBuilder.java - Builder for declarative plugin creation

Modified Files

WorkflowServiceStubs.java - Added newServiceStubs(options, plugins) and ClientPluginCallback interface
WorkflowClientOptions.java - Added plugins field with builder methods
WorkflowClientInternalImpl.java - Applies ClientPlugin.configureClient() during creation
WorkerFactory.java - Full plugin lifecycle (configuration, execution, shutdown)

Test Files (`temporal-sdk/src/test/java/io/temporal/common/plugin/`)

PluginTest.java - Core plugin interface tests
SimplePluginBuilderTest.java - Builder API tests
WorkflowClientOptionsPluginTest.java - Options integration tests

Why?

The plugin system provides a higher-level abstraction over the existing interceptor infrastructure, enabling users to:

Modify configuration during client/worker creation
Wrap execution lifecycles with setup/teardown logic
Auto-propagate plugins from client to worker
Bundle multiple customizations (interceptors, context propagators, etc.) into reusable units

Checklist

Closes Plugin support #2626, and tracked in Plugins to support controlling multiple configuration points at once features#652.
How was this tested:
- Unit tests for all new plugin classes (PluginTest.java, SimplePluginBuilderTest.java, WorkflowClientOptionsPluginTest.java)
- All 21 plugin tests pass
- Full build passes
Any docs updates needed?
- Documentation for the new plugin API should be added to the Java docs

Design Decisions

1. No Base `Plugin` Interface

Decision: ClientPlugin and WorkerPlugin each define their own getName() method independently, rather than sharing a base Plugin interface.

Rationale: This matches the Python SDK's design. Python has separate ClientPlugin and WorkerPlugin with name() on each. I initially had a base Plugin interface but removed it to simplify.

Alternative considered: I could add a shared Plugin interface with just getName(). This would allow List<Plugin> instead of List<?> for storage. However, this adds an interface that serves no purpose other than type convenience, and Python doesn't have it.

2. `ClientPluginCallback` Interface (Module Boundary)

Decision: A ClientPluginCallback interface exists in temporal-serviceclient, which ClientPlugin (in temporal-sdk) extends.

Rationale: This is required due to Java's module architecture:

temporal-serviceclient contains WorkflowServiceStubs
temporal-sdk depends on temporal-serviceclient (not vice versa)
WorkflowServiceStubs.newServiceStubs(options, plugins) needs to call plugin methods
Since serviceclient cannot import from sdk, I define a minimal callback interface in serviceclient

This is the one structural difference from Python, which uses a single-package architecture where everything can import everything else.

3. `PluginBase` Convenience Class

Decision: I provide an abstract PluginBase class that implements both ClientPlugin and WorkerPlugin.

Rationale: This is a common Java pattern (like AbstractList for List).

4. `SimplePluginBuilder` with Private `SimplePlugin`

Decision: I provide a builder for creating plugins declaratively, with the implementation class kept private.

Rationale:

Builder pattern is more natural in Java than Python's constructor with many parameters
Private SimplePlugin is an implementation detail - users interact with the builder
Allows changing implementation without breaking API

PluginBase myPlugin = SimplePluginBuilder.newBuilder("my-plugin")
    .addWorkerInterceptors(new TracingInterceptor())
    .customizeClient(b -> b.setIdentity("custom"))
    .build();

5. No ServiceLoader Discovery

Decision: I do not include ServiceLoader-based plugin discovery.

Rationale:

Python doesn't have this - just uses explicit plugins=[]
ServiceLoader requires classes with no-arg constructors, which doesn't integrate with SimplePluginBuilder
"Magic" discovery is harder to debug than explicit configuration
Explicit plugin configuration is clearer and sufficient

We could consider adding it in though if there is interest.

Example Usage

Custom Plugin

public class TracingPlugin extends PluginBase {
    private final Tracer tracer;

    public TracingPlugin(Tracer tracer) {
        super("my-org.tracing");
        this.tracer = tracer;
    }

    @Override
    public WorkflowClientOptions.Builder configureClient(
            WorkflowClientOptions.Builder builder) {
        return builder.setInterceptors(new TracingClientInterceptor(tracer));
    }

    @Override
    public WorkerFactoryOptions.Builder configureWorkerFactory(
            WorkerFactoryOptions.Builder builder) {
        return builder.setWorkerInterceptors(new TracingWorkerInterceptor(tracer));
    }
}

Using SimplePluginBuilder

PluginBase metricsPlugin = SimplePluginBuilder.newBuilder("my-org.metrics")
    .customizeServiceStubs(b -> b.setMetricsScope(myScope))
    .addWorkerInterceptors(new MetricsInterceptor())
    .build();

Client/Worker with Plugins

WorkflowClientOptions clientOptions = WorkflowClientOptions.newBuilder()
    .setNamespace("default")
    .addPlugin(new TracingPlugin(tracer))
    .addPlugin(metricsPlugin)
    .build();

// Plugins that implement WorkerPlugin auto-propagate to workers
WorkerFactory factory = WorkerFactory.newInstance(client);

Open Questions

Mark as @Experimental? - I've marked all public APIs as @Experimental to allow iteration. Is this appropriate?

CLAassistant · 2026-01-14T14:41:27Z

All committers have signed the CLA.

cretz · 2026-01-14T14:45:36Z

temporal-sdk/src/main/java/io/temporal/common/plugin/ClientPlugin.java

+ * @see PluginBase
+ */
+@Experimental
+public interface ClientPlugin extends ClientPluginCallback {


Is this WorkflowClientPlugin or is it meant to work for ScheduleClient too (and the upcoming standalone activity client and Nexus operation client)?

Let's keep it scoped to just workflows. I think it should be clear now, after I moved it to the appropriate package.

This means that schedule clients can't have plugins? Clients doing schedule things can have plugins in every other SDK (same concern for standalone activity clients coming and Nexus operation clients coming)

Ah i see, i was missing that in Python the big huge Client also includes scheduling stuff, whereass in java they are separate. I'll take a closer look at that.

👍 And note, there are more clients expected to come with standalone activity client and Nexus operation client, but they all will use the same service stubs

temporal-sdk/src/main/java/io/temporal/client/ClientPlugin.java

cretz · 2026-01-14T14:49:50Z

temporal-serviceclient/src/main/java/io/temporal/serviceclient/WorkflowServiceStubs.java

+   * Callback interface for client plugins to participate in service stubs creation. This interface
+   * is implemented by {@code ClientPlugin} in the temporal-sdk module.
+   */
+  interface ClientPluginCallback {


I think we should just consider making a ServiceStubPlugin separate from a WorkflowClientPlugin and if someone wants to implement both, they can. We can discuss whether a plugin here automatically propagates to clients if it implements the proper interface (I think it should, same way client plugins should automatically propagate to workers if the they implement the right interfaces).

cretz · 2026-01-14T14:51:21Z

temporal-serviceclient/src/main/java/io/temporal/serviceclient/WorkflowServiceStubs.java

+   * @return the workflow service stubs
+   */
+  static WorkflowServiceStubs newServiceStubs(
+      @Nonnull WorkflowServiceStubsOptions options, @Nonnull List<?> plugins) {


I think we should accept the plugins on the options and therefore only mutate existing stub construction methods instead of adding a new one. All other SDK implementations of plugins do (acknowledging that plugins should not mutate the plugin list or it's undefined behavior). This makes it easy for users building options separate from where they call this. It also makes it easy to properly apply to the existing overloads like newConnectedServiceStubs. This was done for client, I think it's worth doing here.

temporal-serviceclient/src/main/java/io/temporal/serviceclient/WorkflowServiceStubs.java

temporal-sdk/src/main/java/io/temporal/common/SimplePluginBuilder.java

temporal-sdk/src/main/java/io/temporal/common/plugin/WorkerPlugin.java

temporal-sdk/src/main/java/io/temporal/client/ClientPlugin.java

temporal-sdk/src/main/java/io/temporal/common/plugin/WorkerPlugin.java

…tdownWorkerFactory to SimplePlugin.

cretz · 2026-01-15T16:21:49Z

temporal-sdk/src/main/java/io/temporal/common/SimplePlugin.java

+ * @see WorkerPlugin
+ */
+@Experimental
+public class SimplePlugin implements ClientPlugin, WorkerPlugin {


Pedantic, but if we're not expecting this to be user-instantiable directly and only via builder or extension, could mark it as abstract (not worried about us adding future client/worker plugin methods we forget to implement here, because to be backwards compatible, all future client/worker plugin methods we add will have to have a default)

cretz · 2026-01-15T16:24:54Z

temporal-sdk/src/main/java/io/temporal/common/SimplePlugin.java

+  }
+
+  /** Builder for creating {@link SimplePlugin} instances with declarative configuration. */
+  public static final class Builder {


For a "simple plugin", in addition to interceptors and context propagators, I think users should also be able to directly/simply set data converters, activities, workflows, and Nexus services

donald-pinckney added 3 commits January 14, 2026 09:21

Initial version

4826701

remove discovery, update notes

2440f5e

remove notes

ac87f44

donald-pinckney marked this pull request as ready for review January 14, 2026 15:22

donald-pinckney requested a review from a team as a code owner January 14, 2026 15:22

cretz reviewed Jan 14, 2026

View reviewed changes

donald-pinckney added 5 commits January 14, 2026 15:55

Add initializeWorker in plugin interface.

4d7ef86

Re-do shutdownWorkerFactory design with chain

c37f492

rename runWorkerFactory -> startWorkerFactory

9bf8501

Move plugins around

ad8f70c

add startWorker and shutdownWorker

cd8f340

cretz reviewed Jan 14, 2026

View reviewed changes

temporal-sdk/src/main/java/io/temporal/client/ClientPlugin.java Outdated Show resolved Hide resolved

temporal-sdk/src/main/java/io/temporal/common/plugin/WorkerPlugin.java Outdated Show resolved Hide resolved

donald-pinckney added 6 commits January 15, 2026 08:12

rename again

8168f78

Improved SimplePlugin builder design

0f24727

Remove default implementations, and add in startWorkerFactory and shu…

627dfbc

…tdownWorkerFactory to SimplePlugin.

Don't return the builders

b376be9

Remove ServiceStubsSupplier and checked exception

1d7d5fb

Cleanup applyClientPluginConfiguration

0c3e8ca

cretz reviewed Jan 15, 2026

View reviewed changes

donald-pinckney added 3 commits January 15, 2026 12:19

array instead of list

17ac972

Require ClientPlugin in WorkflowClientOptions

80cf2ba

Seaparate out WorkflowClientPlugin and WorkflowServiceStubsPlugin

1944ba9

Plugin Support for Java SDK #2761

Are you sure you want to change the base?

Plugin Support for Java SDK #2761

Conversation

donald-pinckney commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Plugin System for Java Temporal SDK

What was changed

New Files (temporal-sdk/src/main/java/io/temporal/common/plugin/)

Modified Files

Test Files (temporal-sdk/src/test/java/io/temporal/common/plugin/)

Why?

Checklist

Design Decisions

1. No Base Plugin Interface

2. ClientPluginCallback Interface (Module Boundary)

3. PluginBase Convenience Class

4. SimplePluginBuilder with Private SimplePlugin

5. No ServiceLoader Discovery

Example Usage

Custom Plugin

Using SimplePluginBuilder

Client/Worker with Plugins

Open Questions

Uh oh!

CLAassistant commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cretz Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

donald-pinckney Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

cretz Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

donald-pinckney Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

cretz Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cretz Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

cretz Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cretz Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cretz Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

donald-pinckney commented Jan 14, 2026 •

edited

Loading

New Files (`temporal-sdk/src/main/java/io/temporal/common/plugin/`)

Test Files (`temporal-sdk/src/test/java/io/temporal/common/plugin/`)

1. No Base `Plugin` Interface

2. `ClientPluginCallback` Interface (Module Boundary)

3. `PluginBase` Convenience Class

4. `SimplePluginBuilder` with Private `SimplePlugin`

CLAassistant commented Jan 14, 2026 •

edited

Loading

cretz Jan 14, 2026 •

edited

Loading

cretz Jan 14, 2026 •

edited

Loading

cretz Jan 15, 2026 •

edited

Loading